Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/main.py`:
- Line 35: The import of species module inside the _row_to_payload() function
bypasses the top-level PyTorch gating mechanism, which means history
serialization can crash if PyTorch/TorchVision is unavailable. Move the species
module import and SPECIES_METADATA extraction to the top-level guarded import
block (where the try-except handles PyTorch availability), define a lightweight
fallback SPECIES_METADATA in the except branch for when PyTorch is unavailable,
then replace the dynamic import inside _row_to_payload() with a reference to the
module-level SPECIES_METADATA variable to ensure it uses the pre-initialized
value.

In `@backend/species.py`:
- Around line 95-100: The checkpoint loading code (around line 95-100 in the
conditional branches checking for "model_state_dict") does not validate that the
class-to-index mapping used during training matches the current SPECIES_LABELS
ordering. Modify the checkpoint saving code (referenced in lines 137-146) to
include the species_labels or class_to_idx mapping alongside the
model_state_dict. Then in the checkpoint loading code, extract and validate this
saved mapping against the current SPECIES_LABELS, and either reject the
checkpoint if there is a critical mismatch or apply a remapping transformation
to correct the model output indices before mapping them to species names during
inference.
- Around line 8-10: The torchvision version constraint in requirements.txt is
incompatible with the torch version specified. Update the torchvision constraint
in requirements.txt from the current incompatible version specification to match
the compatible version pair pinned in the Dockerfile (torchvision should be
pinned to version 0.17.2 or use a range like >=0.17.0,<0.18.0 to align with
torch>=2.2.0). This ensures that both the Dockerfile and requirements.txt will
install compatible versions of torch and torchvision, preventing import failures
when installing from requirements.txt.
- Around line 89-104: The torch.load() and load_state_dict() calls in the
species model loading section can raise exceptions from invalid or incompatible
checkpoint files, which will abort the entire startup process. Wrap the
checkpoint loading logic (from torch.load through the load_state_dict call and
model preparation) in a try-except block. When any exception occurs during
loading, catch it, reset the global variables _species_model and _species_loaded
to their initial state, log a warning message about the load failure, and return
early. This ensures species classification remains optional and the application
can continue with the fallback behavior when weights are invalid or
incompatible.

In `@scripts/train_species.py`:
- Around line 21-23: The docstring in lines 21-23 claims the script generates
synthetic training data when no dataset is available, but the actual code at
lines 64-69 calls process.exit(1) when dataset folders are missing,
contradicting this promise. Either update the docstring to accurately reflect
that the script exits when dataset folders are not found, or implement the
synthetic data generation logic that the docstring claims exists. Choose
whichever approach aligns with the intended behavior and make sure the
documentation and actual behavior match.
- Around line 71-84: The ImageFolder class sorts class names alphabetically,
creating indices that don't match the fixed SPECIES_LABELS order used at
inference, causing silent misclassifications. Create a target_transform function
that maps the alphabetically-sorted indices from ImageFolder to the
SPECIES_LABELS order, then apply it to both train_dataset and val_dataset when
creating the ImageFolder instances. Additionally, replace num_classes =
len(class_to_idx) with num_classes = NUM_SPECIES to ensure the model
architecture matches the expected number of species classes and prevents
checkpoint shape mismatches.

---

Outside diff comments:
In `@backend/main.py`:
- Around line 515-529: The issue is that when predict_species() returns a
zero-confidence fallback species (Rohu Carp), the insert statement only stores
the species name without the confidence information, making it indistinguishable
from a real detection in the database history. Fix this by modifying the table
insert for the "species_detected" field to check if the confidence score from
species_info is zero and either store an explicit "unclassified" or "unknown"
value instead of the fallback name, or persist both the species name and its
confidence score together. Apply the same fix in both locations where the scans
table is inserted: in the section around the initial insert (line 515) and in
the second similar insert location mentioned (lines 636-649).

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@scripts/train_species.py`:
- Around line 71-86: The shared ImageFolder remap built from train_dir is being
reused for validation, which can cause split-specific index drift and allow
unexpected labels to slip through. Build and validate the class-to-species
mapping separately for each split in the ImageFolder setup, and make
target_transform fail fast instead of falling back to the raw label so unknown
folders cannot reach CrossEntropyLoss. Use the existing symbols
target_transform, train_dataset, val_dataset, and SPECIES_LABELS to locate and
update the remapping logic.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/train_synthetic.py`:
- Line 8: The synthetic training script duplicates the species labels and model
factory instead of reusing the canonical definitions, so update it to import
SPECIES_LABELS and get_species_model from backend.species rather than
maintaining a separate copy. Remove the unused sys import unless it is needed
for a path setup, and make sure train_synthetic.py references the shared species
model/classifier head symbols so label ordering and architecture stay consistent
with the backend.
- Around line 86-88: The synthetic training script is writing directly to the
same checkpoint filename that production loads via SPECIES_MODEL_PATH, so the
save path must be separated from the deploy path. Update train_synthetic.py so
the model is saved under a distinct output_path (not the hardcoded
Models/species_mobilenetv3.pth target), and use that same output_path
consistently in the save logic around the model serialization steps. Keep
output_dir as the parent folder, but require an explicit copy/rename step before
anything can replace the production checkpoint.
- Around line 125-136: The final save in train_synthetic.py is overwriting the
best checkpoint with the last epoch’s weights, which breaks the save-best
behavior. Update the post-training save logic in the training loop so
species_mobilenetv3.pth is only written when val_acc improves, or otherwise
reload the best checkpoint before the final write; use the existing best_val_acc
tracking and the torch.save call in this function to keep the persisted model
aligned with the reported best validation accuracy.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/fix_and_train.py`:
- Around line 11-14: The `MAPPING` in `fix_and_train.py` is using wrong
substitute species for the `mackerel` and `sardine` training folders. Update the
mapping and the related copy logic in the `fix_and_train` flow to use images of
the actual target species instead of `Hourse Mackerel` and `Black Sea Sprat`,
keeping the `train_real.py` `REAL_SPECIES`/`SYNTHETIC_ONLY` split aligned with
the intended labels.

---

Nitpick comments:
In `@scripts/fix_and_train.py`:
- Around line 130-163: In the training loop in fix_and_train.py, add guards for
zero-sized train or validation splits before computing train_acc and val_acc so
division by zero cannot occur when a loader has no items. Also ensure the Models
output directory exists before the torch.save call in the epoch-best checkpoint
block, using the existing BASE / "Models" path and the current training loop
logic around val_total, train_total, and the save checkpoint.

In `@scripts/generate_synthetic.py`:
- Around line 10-16: The synthetic placeholder colors in missing_species are
only interim fallback data and should not be used as-is for the final dataset.
Update generate_synthetic.py so pangas, basa, and kingfish are also replaced
with real image data sources before those classes are included in any accuracy
reporting, and make sure the synthetic-generation path is clearly limited to
temporary placeholder use alongside the existing fix_and_train.py replacement
flow.
- Around line 21-70: Wrap the script body in a top-level guard so the synthetic
generation logic only runs when the file is executed directly, not when
imported. Move the loop over missing_species, the per-species image generation,
and the final summary printout under an if __name__ == "__main__": block in
generate_synthetic.py, keeping the existing helper/data symbols like SYNTH_DIR,
N_IMAGES, IMG_SIZE, and missing_species unchanged.

In `@scripts/train_real.py`:
- Around line 90-101: Guard the training script against empty input data and a
missing model output folder in scripts/train_real.py. In the main dataset setup
around the combined split and the later training/evaluation block, add a check
after building combined (or before random_split) to fail fast or skip training
when total is 0 so train_correct/train_total cannot divide by zero. Also ensure
the directory used by MODEL_OUT is created before the torch.save call, using the
existing save path logic in the model export section.
- Around line 1-181: The FishDataset class, transform setup, and per-epoch
training/validation loop in train() are duplicated across the training scripts.
Extract the shared dataset, augmentation pipelines, and reusable training loop
into a common train_utils module, then update FishDataset, train(), and the
existing CrowwwDataset/fix_and_train path to call the shared helpers with
species lists and output paths passed in as parameters.